home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / ktrader.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  11.5 KB  |  296 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 2000 Torben Weis <weis@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License version 2 as published by the Free Software Foundation.
  7.  
  8.    This library is distributed in the hope that it will be useful,
  9.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.    Library General Public License for more details.
  12.  
  13.    You should have received a copy of the GNU Library General Public License
  14.    along with this library; see the file COPYING.LIB.  If not, write to
  15.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18. #ifndef __ktrader_h__
  19. #define __ktrader_h__
  20.  
  21. #include <qstring.h>
  22. #include <qobject.h>
  23. #include <kservice.h>
  24.  
  25. /**
  26.  * A Trader interface, similar to the CORBA Trader.
  27.  *
  28.  * Basically, it provides a way for an application to query
  29.  * all KDE services (that is, applications and components) that match
  30.  * a specific set of requirements.  This allows you to find an
  31.  * application in real-time without you having to hard-code the name
  32.  * and/or path of the application.
  33.  *
  34.  * \par Examples
  35.  *
  36.  * A few examples will make this a lot more clear.
  37.  *
  38.  * Say you have an application that will display HTML.  In this
  39.  * example, you don't want to link to khtml... and furthermore, you
  40.  * really don't care if the HTML browser is ours or not, as long as
  41.  * it works.  The way that you formulate your query as well as the way
  42.  * that you execute the browser depends on whether or not you want the
  43.  * browser to run stand-alone or embedded.
  44.  *
  45.  * If you want the browser to run standalone, then you will limit the
  46.  * query to search for all services that handle 'text/html' @em and,
  47.  * furthermore, they must be applications (Type=Application).  You
  48.  * then will use KRun::run() to invoke the application.  In "trader-speak",
  49.  * this looks like this:
  50.  * \code
  51.  * KTrader::OfferList offers = KTrader::self()->query("text/html", "Type == 'Application'");
  52.  * KService::Ptr ptr = offers.first();
  53.  * KURL::List lst;
  54.  * lst.append("http://www.kde.org/index.html");
  55.  * KRun::run(*ptr, lst);
  56.  * \endcode
  57.  *
  58.  * Now, say that you want to list all KParts component that can handle HTML. 
  59.  * \code
  60.  * KTrader::OfferList offers = KTrader::self()->query("text/html", "KParts/ReadOnlyPart");
  61.  * \endcode
  62.  *
  63.  * If you want to get the preferred KParts component for text/html you could use
  64.  * KServiceTypeProfile::preferredService("text/html", "KParts/ReadOnlyPart"), although if this is about
  65.  * loading that component you would rather use KParts::ComponentFactory directly.
  66.  *
  67.  *
  68.  * Please note that when including property names containing arithmetic operators like - or +, then you have
  69.  * to put brackets around the property name, in order to correctly separate arithmetic operations from
  70.  * the name. So for example a constraint expression like
  71.  *  X-KDE-Blah < 4
  72.  * needs to be written as
  73.  * [X-KDE-Blah] < 4
  74.  * otherwise it could also be interpreted as
  75.  * Substract the numeric value of the property "KDE" and "Blah" from the property "X" and make sure it
  76.  * is less than 4.
  77.  * Instead of the other meaning, make sure that the numeric value of "X-KDE-Blah" is less than 4.
  78.  *
  79.  * See also the formal syntax defined in @ref tradersyntax .
  80.  *
  81.  * @short Provides a way to query the KDE infrastructure for specific
  82.  *        applications or components.
  83.  * @author Torben Weis <weis@kde.org>
  84.  */
  85. class KIO_EXPORT KTrader : public QObject
  86. {
  87.     Q_OBJECT
  88. public:
  89.     /**
  90.      * A list of services.
  91.      */
  92.     typedef QValueList<KService::Ptr> OfferList;
  93.     typedef QValueListIterator<KService::Ptr> OfferListIterator;
  94.  
  95.     /**
  96.      * Standard destructor
  97.      */
  98.     virtual ~KTrader();
  99.  
  100.     /**
  101.      * The main function in the KTrader class.
  102.      *
  103.      * It will return a list of services that match your
  104.      * specifications.  The only required parameter is the service
  105.      * type.  This is something like 'text/plain' or 'text/html'.  The
  106.      * constraint parameter is used to limit the possible choices
  107.      * returned based on the constraints you give it.
  108.      *
  109.      * The @p constraint language is rather full.  The most common
  110.      * keywords are AND, OR, NOT, IN, and EXIST, all used in an
  111.      * almost spoken-word form.  An example is:
  112.      * \code
  113.      * (Type == 'Service') and (('KParts/ReadOnlyPart' in ServiceTypes) or (exist Exec))
  114.      * \endcode
  115.      *
  116.      * The keys used in the query (Type, ServiceType, Exec) are all
  117.      * fields found in the .desktop files.
  118.      *
  119.      * @param servicetype A service type like 'text/plain', 'text/html', or 'KOfficePlugin'.
  120.      * @param constraint  A constraint to limit the choices returned, QString::null to
  121.      *                    get all services of the given @p servicetype
  122.      * @param preferences Indicates a particular preference to return, QString::null to ignore.
  123.      *                    Uses an expression in the constraint language that must return
  124.      *                    a number
  125.      *
  126.      * @return A list of services that satisfy the query
  127.      * @see http://developer.kde.org/documentation/library/3.5-api/kdelibs-apidocs/kio/kio/html/tradersyntax.html
  128.      */
  129.     virtual OfferList query( const QString& servicetype,
  130.                  const QString& constraint = QString::null,
  131.                  const QString& preferences = QString::null) const;
  132.  
  133.     /**
  134.      * A variant of query(), that takes two service types as an input.
  135.      * It is not exactly the same as adding the second service type
  136.      * in the constraints of the other query call, because this one
  137.      * takes into account user preferences for this combination of service types.
  138.      *
  139.      * Example usage:
  140.      * To get list of applications that can handle a given mimetype,
  141.      * set @p servicetype to the mimetype and @p genericServiceType is "Application".
  142.      * To get list of embeddable components that can handle a given mimetype,
  143.      * set @p servicetype to the mimetype and @p genericServiceType is "KParts/ReadOnlyPart".
  144.      *
  145.      * @param servicetype A service type like 'text/plain', 'text/html', or 'KOfficePlugin'.
  146.      * @param genericServiceType a basic service type, like 'KParts/ReadOnlyPart' or 'Application'
  147.      * @param constraint  A constraint to limit the choices returned, QString::null to
  148.      *                    get all services of the given @p servicetype
  149.      * @param preferences Indicates a particular preference to return, QString::null to ignore.
  150.      *                    Uses an expression in the constraint language that must return
  151.      *                    a number
  152.      *
  153.      * @return A list of services that satisfy the query
  154.      * @see http://developer.kde.org/documentation/library/kdeqt/tradersyntax.html
  155.      */
  156.     OfferList query( const QString& servicetype, const QString& genericServiceType,
  157.                      const QString& constraint /*= QString::null*/,
  158.                      const QString& preferences /*= QString::null*/) const;
  159.  
  160.     /**
  161.      * This is a static pointer to a KTrader instance.
  162.      *
  163.      *  You will need
  164.      * to use this to access the KTrader functionality since the
  165.      * constuctors are protected.
  166.      *
  167.      * @return Static KTrader instance
  168.      */
  169.     static KTrader* self();
  170.  
  171. protected:
  172.     /**
  173.      * @internal
  174.      */
  175.     KTrader();
  176.  
  177. private:
  178.     static KTrader* s_self;
  179. protected:
  180.     virtual void virtual_hook( int id, void* data );
  181. };
  182.  
  183. /** @page tradersyntax Trader Syntax
  184.  *
  185.  *
  186.  * @section Literals
  187.  *
  188.  * As elementary atoms of the constraint language, KTrader supports
  189.  * booleans, integers, floats and strings. Boolean literals are
  190.  * @a TRUE and @a FALSE . Integers can be positive or negative,
  191.  * i.e. @a 42 and @a -10 are legal values. Floating point
  192.  * numbers are @a 3.141592535 or @a -999.999 . Scientific notation
  193.  * like @a 1.5e-2 is not supported. Character literals are delimited
  194.  * by single quotation marks, e.g. @a 'Bernd' .
  195.  *
  196.  *
  197.  * @section Symbols
  198.  *
  199.  * Identifiers in query string are interpreted as property names, which
  200.  * are listed in the service's <tt>.desktop</tt> file. For example,
  201.  * <tt>Name</tt> is the name of the service, <tt>ServiceTypes</tt> is a
  202.  * list of the service types it supports. Note that only properties can
  203.  * be written as-is which start with an alphabetical character and contain
  204.  * only alphanumerical characters. Other properties have to be enclosed in
  205.  * brackets, e.g. <tt>[X-KDE-Init]</tt>. Properties must not contain any
  206.  * special characters other than <tt>-</tt>.
  207.  *
  208.  * Special property names:
  209.  *   - <b>DesktopEntryName</b> stands for the filename of the service
  210.  *     desktop entry without any extension. This can be useful to
  211.  *     exclude some specific services.
  212.  *   - <b>DesktopEntryPath</b> stands for the relative or full path
  213.  *     to the .desktop file, see KService::desktopEntryPath. Mentionned
  214.  *     here for completeness, better not use it (things can be moved
  215.  *     around).
  216.  *   - <b>Library</b> is the property whose value is set by
  217.  *     <tt>X-KDE-Library</tt> in the .desktop file. This renaming
  218.  *     happened to conform to the desktop file standard, but the
  219.  *     property name didn't change.
  220.  *
  221.  *
  222.  * @section Comparison
  223.  *
  224.  * Supported comparison operators are:
  225.  *
  226.  *   - <tt>==</tt>
  227.  *   - <tt>!=</tt>
  228.  *   - <tt><</tt>
  229.  *   - <tt><=</tt>
  230.  *   - <tt>></tt>
  231.  *   - <tt>>=</tt>
  232.  *
  233.  *
  234.  * @section Arithmetic Arithmetic and boolean expressions
  235.  *
  236.  *   - <tt>+</tt>
  237.  *   - <tt>-</tt>
  238.  *   - <tt>*</tt>
  239.  *   - <tt>/</tt>
  240.  *   - <tt>and</tt>
  241.  *   - <tt>or</tt>
  242.  *   - <tt>not</tt>
  243.  *
  244.  * Note that the arithmetic operators are possible for integers and
  245.  * floating point numbers. <tt>-</tt> is both a unary and binary operator,
  246.  * <tt>not</tt> is a unary operator.
  247.  *
  248.  *
  249.  * @section Other Other operators
  250.  *
  251.  *   - <tt>~</tt>
  252.  *   - <tt>in</tt>
  253.  *   - <tt>exist</tt>
  254.  *   - <tt>()</tt>
  255.  *
  256.  * The tilde operator stands for a substring match. For example,
  257.  * <tt>KParts ~ 'KParts/ReadOnlyPart'</tt> is TRUE. The membership
  258.  * operator <tt>in</tt> tests whether a value is in a list. A list is a
  259.  * string with semi-colon- or comma-separated entries, depending on the
  260.  * type. An example for the membership operator is
  261.  * <tt>'text/plain' in ServiceTypes</tt>.
  262.  * The <tt>exist</tt> tests whether a certain property is defined in the
  263.  * <tt>.desktop</tt> file. Subexpressions are written in parentheses.
  264.  *
  265.  * Warning, testing the contents of a property only works if the property
  266.  * is specified. There is not support for default values. If the property
  267.  * might be missing, and you still want such services to be included, you
  268.  * have to check for existence before testing it. For instance, to say
  269.  * that MyProp is a boolean that defaults to true, and that you want the
  270.  * services that have it set to true, use:
  271.  * <tt>not exist MyProp or MyProp</tt>
  272.  * Simply testing for <tt>MyProp</tt> would
  273.  * exclude the services without the property at all.
  274.  *
  275.  *
  276.  * @section Examples
  277.  *
  278.  * The following examples show filters for .desktop files.
  279.  * <tt>Type</tt>, <tt>ServiceTypes</tt> and <tt>MimeType</tt> are
  280.  * properties in .desktop files. Be aware that within KTrader MimeType
  281.  * properties are understood as ServiceTypes ones.
  282.  *
  283.  *
  284.  *   - <tt>Type == 'Application'</tt>@n
  285.  *     All services that are applications.
  286.  *   - <tt>'KParts/ReadOnlyPart' in ServiceTypes</tt>@n
  287.  *     All read-only KParts.
  288.  *   - <tt>('KParts/ReadOnlyPart' in ServiceTypes) and ('text/plain' in ServiceTypes)</tt>@n
  289.  *     All read-only KParts that handle the mime type 'text/plain'.
  290.  *
  291.  * @author Bernd Gehrmann <a href="mailto:bernd@kdevelop.org">bernd@kdevelop.org</a>
  292. */
  293.  
  294.  
  295. #endif
  296.